KCGetAttribute

KCGetAttribute
Header:	Keychain.h		Carbon status:	Under Evaluation

Determines keychain item data using a keychain item attribute structure.

OSStatus KCGetAttribute (
    KCItemRef item, 
    KCAttribute *attr, 
    UInt32 *actualLength
);

Parameter descriptions

item: A reference to the keychain item whose attribute data you wish to determine.
attr: A pointer to a structure of type KCAttribute. Before calling KCGetAttribute, fill in the tag, length, and data fields (the data field should contain a pointer to a buffer of sufficient length for the type of data to be returned). On return, KCGetAttribute will pass back the requested data in the data field.
actualLength: On return, a pointer to the actual length of the attribute data. This may be more than the length you allocated in the length field of the attribute structure.

function result: A result code. The result code errKCInvalidItemRef indicates that the specified keychain item reference was invalid. The result code errKCNoSuchAttr indicates that you tried to set an attribute which is undefined for this item class. The result code errKCBufferTooSmall indicates that your application must allocate a new buffer of sufficient size before calling KCGetAttribute again.

DISCUSSION

You can call KCGetAttribute or the function KCGetData to obtain keychain item data. The difference between the functions is that KCGetData requires that you pass the length of the data and a pointer to that data as separate parameters rather than fields in a keychain item attribute structure.

If the keychain that contains the item is locked, before calling KCGetAttribute you should call the function KCUnlock to prompt the user to unlock the keychain.

You can determine any of the standard item attributes identified by the following tag constants: kClassKCItemAttr, kCreationDateKCItemAttr, kModDateKCItemAttr, kDescriptionKCItemAttr, kCommentKCItemAttr, kLabelKCItemAttr, kCreatorKCItemAttr, kScriptCodeKCItemAttr, and kCustomIconKCItemAttr. There is additional data you can determine, depending upon the type of keychain item whose data you wish to obtain. See “Keychain Item Data Tag Constants” for more information.

VERSION NOTES

Available beginning with Keychain Manager 1.0.